Skip to content

docs: explain how to collect coverage from web workers - #1012

Merged
jennifer-shehane merged 3 commits into
masterfrom
claude/webworker-coverage-docs-v6nvv5
Nov 2, 2026
Merged

jennifer-shehane merged 3 commits into
masterfrom
claude/webworker-coverage-docs-v6nvv5

Conversation

@jennifer-shehane

@jennifer-shehane jennifer-shehane commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

Additional details

Why does code running in a Web Worker never show up in the report? The support hooks only read __coverage__ from the app window and the spec window (lib/support.ts). An instrumented worker keeps its counters on its own global, self.__coverage__, so the plugin never sees them.

This PR doesn't change any code. It adds a Coverage from web workers section to README.md, right after the backend coverage docs, with a workaround people can copy:

  • Instrument the worker: make sure the bundler instruments the worker file too, and log self.__coverage__ inside the worker to confirm it.
  • Worker side: a guarded message listener sends self.__coverage__ back over a MessageChannel port, so the app's own main-thread message handlers never see the reply.
  • Support file: wrap win.Worker in window:before:load to keep track of each worker. After each test, ask every worker for its coverage, with a 1-second timeout for workers that won't answer, and send each reply to the existing combineCoverage task.
  • Limits: a worker's counters disappear when the worker ends, each worker reports once at the end of the test that started it, and shared workers and service workers aren't covered.

A first-class API (for example, a collectCoverage() command) could come later, but it's out of scope here.

Steps to test

  1. Read the new section in the rendered README.
  2. Optional, the happy path: in an app with an instrumented dedicated worker, add the worker snippet and the support-file snippet, run a spec that uses the worker, and check that the worker's file appears in coverage/ with the expected hit counts.

What I verified:

  • npm run build, npm test (30 passed) and npm run format:check pass.
  • I ran the example in headless Chromium, with the app and spec in separate same-origin iframes the way Cypress sets them up, and a worker instrumented by Istanbul. The merged coverage showed real hit counts (a called function at 1, an uncalled one at 0). A terminated worker timed out to null instead of hanging, and the app's main-thread handler only saw its own message.
  • I couldn't run the example inside Cypress itself because the Cypress binary wouldn't download in my environment, so a real Cypress run of the snippets would be really welcome.
  • npm run check:markdown couldn't reach outside hosts from my environment, so every GitHub link failed on master too, and so did the two new MDN links. CI will give the real result.

How has the user experience changed?

No change to how the plugin behaves. The README gains a new section on collecting coverage from web workers.


Generated by Claude Code


Note

Low Risk
Documentation-only change with no runtime or plugin behavior changes.

Overview
Adds a Coverage from web workers section to README.md (after the backend coverage docs) explaining why worker code is absent from reports and how to merge it manually.

The new text states that the plugin only reads window.__coverage__ from app and spec windows, while instrumented workers keep counters on self.__coverage__. It documents a copy-paste workaround: instrument the worker bundle, respond to a cypress:coverage message over a MessageChannel, track new Worker() instances from the Cypress support file, collect coverage in afterEach, and forward each payload to the existing combineCoverage task.

It also calls out limits—coverage must be collected before the worker ends, each worker is polled once per test, and dedicated workers only (not shared or service workers).

Reviewed by Cursor Bugbot for commit e56f413. Bugbot is set up for automated code reviews on this repo. Configure here.

The support hooks read `__coverage__` from the app and spec windows only.
An instrumented dedicated worker keeps its counters on its own global, so
its code never reached the report. Document a workaround: the worker
replies to a coverage request over a MessageChannel, and an afterEach
hook in the support file sends each reply to the combineCoverage task.

Refs #102

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WUv8r3qbyBkGWEnvGWtCrX
Soften the lead-in to the workaround's limits, drop a step count that
didn't match the list, and nest the code samples under their steps so
the numbered list renders as one list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WUv8r3qbyBkGWEnvGWtCrX
@jennifer-shehane
jennifer-shehane merged commit a074d50 into master Nov 2, 2026
32 checks passed
@jennifer-shehane
jennifer-shehane deleted the claude/webworker-coverage-docs-v6nvv5 branch November 2, 2026 00:11
@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

🎉 This PR is included in version 4.1.3 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

No Coverage reported for WebWorkers

2 participants